home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / EDITORS / ZAP130 / !Zap / Docs / E-File < prev    next >
Text File  |  1995-02-20  |  10KB  |  257 lines
  1. *************************************************************************
  2. * >E-File    Documents a file block format                *
  3. *************************************************************************
  4.  
  5. By convention, file blocks are pointed to by R9. However, whenever a file is
  6. created, the file block pointers of the other files may change. Hence these
  7. pointers are not preserved across calls to Wimp_Poll. Thus they must be
  8. converted to file block 'offsets' (ie 0=first file,1=second etc) for storing
  9. as pointers or links. The calls Zap_ConvFileOff and Zap_GetFileOff can be
  10. used to do this. The number of valid file block offsets may be got by
  11. Zap_ReadVar. (Then valid offsets are 0 1 ... n-1)
  12.  
  13. The length of a file block is not fixed and varies across versions of zap.
  14. Thus you must not assume a fixed length. If you must know the length then
  15. convert file offsets 0,1 to pointers and then subtract them. The offsets from
  16. the file block start are given names beginning with 'f_'.
  17.  
  18. See the E-Library file for a list of the 'f_' names. You should use code of
  19. the form:
  20.  
  21.     LDR R0,[R9,#f_ptr]        \ set R0 to start of file buffer.
  22.     
  23. to read these variables.
  24.  
  25. The files themselves are stored in SPLIT BUFFER format. This means that the
  26. file data is split in two, with a gap in the middle. The diagram below should
  27. illustrate this.
  28.  
  29.         ------------------------ f_ptr+f_bufl
  30.         | top half of file     |
  31.         ------------------------ f_ptr+f_splite
  32.         | file gap           |
  33.         ------------------------ f_ptr+f_splito
  34.         | bottom half of file  |
  35.         ------------------------ f_ptr
  36.         
  37. NB For all Zap data structures block_start=first byte of data, block_end=
  38. last byte of data+1, block_length=block_end-block_start.
  39.  
  40. Note that f_ptr may change on any heap block claim, or file insert/delete.
  41. Thus all the other variables are stored as offsets from this. You should use
  42. the call Zap_SplitBuffer to change the buffer length or split position. You
  43. should use the call Zap_Command to insert/delete data. Inserting data
  44. manually and keeping all the variables/undo buffer/screen updated requires a
  45. lot of code if you want to do it yourself (the only exception to this is the
  46. e_postload/e_presave calls where it is quicker to manipulate the file
  47. directly).
  48.  
  49. For most subs in Zap, a position in the file is given as an offset from the
  50. file start (in the range 0 to the length of the file). These file offsets
  51. should not be confused with the file block offsets described in the first
  52. paragraph. When I say 'file offset', it should be clear from the context what
  53. I mean.
  54.  
  55. To read the byte at offset R0 you should use code of the form:
  56.  
  57.     REM R0=file offset R9=file
  58.     REM On exit R1 corrupted and R0=byte read.
  59.  
  60.     LDR R1,[R9,#f_splito]        \ find the split offset in the buffer
  61.     CMP R0,R1            \ are we in the bottom or top half?
  62.     LDRCS R1,[R9,#f_splits]
  63.     ADDCS R0,R0,R1            \ if in the top half, skip the split
  64.     LDR R1,[R9,#f_ptr]        \ start address of file
  65.     LDRB R0,[R1,R0]            \ read the byte
  66.  
  67. To read multiple bytes you should obviously use more efficient code! If
  68. you are doing a very intensive operation then you may want to coagulate
  69. the text via Zap_SplitBuffer. The file variables are detailed below. Use
  70. E-Library to set them up.
  71.  
  72. f_ptr
  73. Address of file buffer/-1 if file is dead (has been deleted). If you scan
  74. through the file blocks, you should always check this word to check the file
  75. is not dead.
  76.  
  77. f_bufl
  78. Length of file buffer (multiple of 4). See pic above.
  79.  
  80. f_len
  81. Length of file stored in the buffer (=f_bufl-f_splits).
  82.  
  83. f_name
  84. Pointer to name of the file.
  85.  
  86. f_load
  87. Load address of the file.
  88.  
  89. f_exec
  90. Execution address of the file.
  91.  
  92. f_flags
  93. File flags. See E-Flags for the meaning of the bits in this word.
  94.  
  95. f_uptr
  96. Pointer to the undo buffer. The undo buffer consists of a list of blocks of
  97. variable length. The start of a block is indicated by bit 31 of that word
  98. being set. In general the first word of the block has format:
  99.     b31 =1 (Set to indicate block start).
  100.     b30 Set if the command should be undone in one go. (as opposed to one
  101.         character at a time for concatenated blocks).
  102.     b29 Set if the data pointed to by the command need not be freed.
  103.     (This is used on an undo when blocks are pointed to twice).
  104.     b26-b28 Command number. As for R0 in Zap_Command with additions:
  105.         0 = fast undo pointer (fast redo if b30 set)
  106.         7 = startop pointer (stopop pointer if b30 set)
  107.     b0-b27 Gives the commands first parameter, usually a file offset
  108.         This corresponds to register R1 in Zap_Command.
  109. The other words correspond to registers R2 onwards when calling Zap_Command.
  110.  
  111. f_ubufl
  112. Total length of the undo buffer.
  113.  
  114. f_ulen
  115. Length of valid data in the undo buffer.
  116.  
  117. f_undo
  118. Offset of the undo pointer in the undo buffer.
  119.  
  120. f_undop
  121. Offset of the undo subpointer in the block pointer to by f_undo. Ie it gives
  122. the number of characters left to undo in the operation currently being
  123. undone.
  124.  
  125. f_blklen
  126. This gives the total length of the file buffer followed by the undo data
  127. which is tagged onto it in later versions of Zap. (Ie, it is >=f_bufl).
  128.  
  129. f_splito
  130. Offset in the file buffer of the current split position. See pic.
  131.  
  132. f_splite
  133. Offset in the file buffer of the end of the current split. See pic.
  134.  
  135. f_splits
  136. Size of the file split (=f_splite-f_splito). See pic.
  137.  
  138. f_mptr
  139. Pointer to the marker buffer. The marker buffer is a list of entries, each
  140. two words longs of the format:
  141.     #0    File offset of the mark
  142.     #4    Window offset of the window mark was place in or -1 if the
  143.         window has been deleted (or is unspecified).
  144.  
  145. f_mbufl
  146. Length of the marker buffer.
  147.  
  148. f_mlen
  149. Length of valid data in the marker buffer.
  150.  
  151. f_mark
  152. Current offset in the marker buffer.
  153.  
  154. f_docom
  155. Used by Zap_SaveTxtStatus: stores the current action (as for Zap_DoCommand
  156. bits 0-2) ie, 1=insert text 2=delete text 3/4=replacement of text.
  157.  
  158. f_source
  159. This word is for the use of the mode 'owning' this file. See f_cmode. It
  160. usually points to a data block of info that mode wants to hold for this file.
  161. Current formats used are:
  162.  f_cmode    f_source meaning
  163.  0 (Text)    Text mode owns external edit files and handles them. f_source
  164.          points to the block:
  165.          #0    External edit JOB handle (Zaps part of the job
  166.              handle is the file block offset+1)
  167.          #4    Task handle of client task
  168.          #8    Flags passed by client when job started
  169.          #12    Offset in window block of associated window.
  170.  1 (Byte)    Byte mode owns 'read disc' files. f_source is the disc
  171.          address the file was read from.
  172.  11 (Throwback) Task handle of task that sent throwback data.
  173.  12(Taskwindow) Taskwindow mode owns taskwindow files. f_source points to
  174.          a block of the format:
  175.          #0    Task handle of child task
  176.          #4    Cursor x posn (chars)
  177.          #8    Cursor y posn (chars)
  178.          #12    Height of emulated screen (chars)
  179.          #16    Text window min x (chars)
  180.          #20    Text window min y (chars)
  181.          #24    Text window max x (chars)
  182.          #28    Text window max y (chars)
  183.          #32    Number of bytes stored in the VDU queue.
  184.          #36    12 byte buffer to store the VDU queue in.
  185.          #48    Offset in window block of associated window.
  186.          #52    Flags:    b0    Set if task suspended
  187.                  b1    internal use
  188.          #56    Line offset from work area start of emulated screen.
  189.         w_bpl stores the width of the emulated screen.
  190.  
  191. f_dolen
  192. Used by Zap_SaveTxtStatus: Stores the size of the data being inserted/
  193. deleted/replaced.
  194.  
  195. f_dodata
  196. Used by Zap_SaveTxtStatus: Stores the address of the data being inserted/
  197. replaced.
  198.  
  199. f_altered
  200. Used by Zap_DoCommand: First altered offset in file / -1
  201.  
  202. f_shiftable
  203. Used by Zap_DoCommand: First unaltered offset in file / -1
  204.  
  205. f_change
  206. Used by Zap_DoCommand: Signed change in size of data.
  207.  
  208. f_depth
  209. Used by Zap_StartOp: Current StartOp/StopOp nested depth.
  210.  
  211. f_links
  212. Links list buffer pointer. This is most used by 'throwback' though may
  213. have other uses. The idea is that this block stores references to offsets
  214. in other files. When these files are updated, the offsets are updated too
  215. so you can keep track of that point in the file. Use Zap_NewLinkEntry to add
  216. a new link. f_links points to a list of 16 byte blocks terminated by -1. The
  217. block format is
  218.     #0    Pointer to file name of associated file (with match/error)
  219.         (Eg this is the C source file corresponding to this throwback
  220.         file).
  221.     #4    Pointer to a list of search/error, offsets/line numbers.
  222.         The list is terminated by -1.
  223.         (These are the offsets to be updated when changes are made
  224.         to the file with name #0 and file block offset in #8).
  225.     #8    Offset of file (name given in #0) if already loaded into Zap.
  226.         -1 if file has not been looked for. If the file is loaded
  227.         then any changes to the file cause the list in #4 to be
  228.         updated.
  229.     #12    Flags:    b0    Set if #4 points to line nums, not offsets.
  230.                 The line numbers are converted to offsets
  231.                 when throwback mode loads the file.
  232.             b1-b7    reserved
  233.             b8-b15    Number of lines heading each block.
  234.                 The format of the throwback buffer must
  235.                 be <file header para> <list of matches para>
  236.                 <next file header para> etc. This details
  237.                 the number of lines of heading/info that the
  238.                 <list of matches para> starts off with
  239.                 before listing the matches (at one match
  240.                 per line corresponding to the offsets
  241.                 pointed to by #4).
  242.             b16-b23    Source: (for info purposes)
  243.                 0=Search throwback (F7)
  244.                 1=C Throwback (Eg !CC)
  245.                 2=C Info (Eg !Find).
  246.             b24-b31 reserved
  247.  
  248. f_cmode
  249. This gives the mode number of the mode 'owning' this file (-1 if none). The
  250. mode is called when the file is deleted (eg a taskwindow). The mode may use
  251. the word f_source to store parameters about the file. (Eg f_source will
  252. usually be set by the extension mode to point to a data block). To claim the
  253. file, simply check that this word is -1 and then poke your mode number in.
  254. Use the entry point e_init with reason code 3 to free any data you have
  255. stored associated with this file (and pointed to by f_source). This mode is
  256. NOT necessarily the mode the file is displayed in.
  257.